SAS (Smart Assemble System) - System Design Document

1. Overview
2. Architecture Philosophy
3. High-Level Architecture
4. System Components
5. Technology Stack
6. Database Design
7. Asynchronous Processing
8. Deployment Architecture
9. Scaling Strategy
10. Integration Patterns
11. Performance Optimization
12. Monitoring & Observability
13. Security Considerations
14. Disaster Recovery
15. Summary

1. Overview

SAS (Smart Assemble System) is a comprehensive health insurance management platform designed to handle end-to-end insurance operations including sales, underwriting, membership management, claims processing, provider network management, and customer relationship management.

1.1 Key Characteristics

Modular Monolith: Single Django application organized into focused modules (apps)
Single Database: One PostgreSQL database with logical separation via table prefixes
Horizontal Scaling: Multiple Django instances behind load balancer
Async Processing: Celery workers for heavy/long-running tasks
AI/ML Separation: FastAPI service for ML workloads
On-Premise Deployment: Docker Swarm for container orchestration

1.2 Why This Architecture?

Simple to develop and maintain
Easy to debug without distributed tracing complexity
Straightforward deployment process
Database transactions work normally with ACID guarantees
Modules can be refactored without service boundaries
Clear migration path to microservices if needed later

2. Architecture Philosophy

2.1 Modular Monolith Principles

One Codebase, Multiple Modules: All business logic in one Django project, organized as Django apps
Shared Database: Single source of truth, ACID (Atomic, Consistent, Isolation, Durability) transactions, simple queries
Clear Boundaries: Each Django app has well-defined responsibilities
Async Where Needed: Heavy tasks delegated to Celery workers
Scale the Whole App: Add more Django instances, not individual services

2.2 What We're NOT Doing

Not Microservices: No separate deployments per module
Not Database-per-Service: One database cluster, not multiple isolated databases
Not Service Mesh: No complex inter-service communication
Not Event Sourcing: CRUD with events for async tasks only

3. High-Level Architecture

4. System Components

4.1 Client Applications

Frontend applications that interact with the SAS platform via subdomain-based routing.

4.1.1 Admin Portal (React)

Subdomain: admin.sas.assemble.com

Purpose: Internal staff administrative interface

Target Users:

Admins
Underwriters
Claims processors
Finance officers
Customer service representatives

Key Features:

Dashboard with system-wide metrics
Member enrollment and management
Policy creation and management
Claims adjudication interface
Provider network management
User management and RBAC
Reports and exports
System configuration

Authentication: Active Directory (LDAP) via SSO

Technology: React 19

4.1.2 Member Portal (React)

Subdomain: member.sas.assemble.com

Purpose: Self-service portal for insurance members

Target Users: Insurance members

Key Features:

View active policies and benefits
Digital member card with QR code
Submit and track claims
Upload claim documents
View claim history and status
Update personal information
Download policy documents
Access wellness programs
Message customer service

Authentication: Database authentication with email/password

Technology: React 19

4.1.3 Provider Portal (React)

Subdomain: provider.sas.assemble.com

Purpose: Healthcare provider interface

Target Users: Hospitals, clinics, doctors, pharmacies

Key Features:

Check member eligibility in real-time
Submit claims electronically
View claim status and history
Access provider contracts
View payment history
Update provider credentials
Network directory access
Submit pre-authorization requests

Authentication: Database authentication with credentials management

Technology: React 19

4.1.4 Agent Portal (React)

Subdomain: agent.sas.assemble.com

Purpose: Insurance agent and broker interface

Target Users: Sales agents and brokers

Key Features:

Lead management
Generate policy quotes
Enroll new members
Track commissions and earnings
View sales pipeline and reports
Access marketing materials
Member search and lookup
Performance dashboards

Authentication: Database authentication with agent credentials

Technology: React 19

4.1.5 BI Dashboard (React)

Subdomain: bi.sas.assemble.com

Purpose: Analytics and business intelligence dashboards

Target Users:

Management and executives
Finance team
Underwriting team
Operations team

Key Features:

Real-time metrics and KPIs
Claims analytics and trends
Financial reports and forecasts
Member enrollment statistics
Interactive charts and visualizations
Customizable dashboards
Export capabilities
Scheduled report generation

Authentication: Active Directory (LDAP) via SSO

Technology: React 19 with D3.js/Chart.js

4.1.6 Mobile App (Flutter)

Purpose: iOS and Android apps for members and providers

Target Users:

Members: View policies, submit claims, access member cards
Providers: View claims, submit bills, check eligibility

Key Features:

Digital member card with QR code
Claims submission with document upload
Policy information and benefits
Provider search and network directory
Push notifications
Biometric authentication

Technology: Flutter for cross-platform development

4.1.7 Access Patterns & Subdomains

Subdomain Strategy: Separate subdomains for different user types

Subdomain Structure:

admin.sas.assemble.com - Internal staff portal
member.sas.assemble.com - Member self-service portal
provider.sas.assemble.com - Provider portal
agent.sas.assemble.com - Agent/Broker portal
bi.sas.assemble.com - Business intelligence dashboard
api.sas.assemble.com - REST API endpoints

Benefits of Subdomain Separation:

Security Isolation:

Each subdomain has isolated cookies and sessions
XSS vulnerabilities in one portal don't compromise others
Different Content Security Policy (CSP) per subdomain
Protects sensitive health data (biometric, claims, medical records)

Authentication Differentiation:

Internal users (admin, bi) → Active Directory SSO
External users (member, provider, agent) → Database authentication
Each subdomain shows appropriate login page
No confusion between authentication methods

User Experience:

Clear separation prevents users from accessing wrong portals
Member-specific branding on member.sas.assemble.com
Provider-specific workflows on provider.sas.assemble.com
Simplified navigation - only relevant features shown

Scaling & Performance:

Each portal can be scaled independently
Member portal (high traffic) can have more replicas
BI dashboard (low traffic) can have fewer resources
Separate cache strategies per portal

SSL/TLS Configuration:

Wildcard Certificate: *.sas.assemble.com

Single certificate covers all subdomains
Easier management than individual certificates
Traefik automatically handles certificate routing

Certificate Provider: Let's Encrypt or commercial CA

Automatic renewal via cert-manager
TLS 1.2+ enforced
HSTS headers for security

Routing with Traefik:

Load Balancer Configuration:

# Example Traefik routing rules
admin.sas.assemble.com → admin-portal:3000
member.sas.assemble.com → member-portal:3000
provider.sas.assemble.com → provider-portal:3000
agent.sas.assemble.com → agent-portal:3000
bi.sas.assemble.com → bi-dashboard:3000
api.sas.assemble.com → django-cluster:8000

Traffic Flow:

User accesses member.sas.assemble.com
DNS resolves to load balancer IP
Traefik inspects Host header
Routes to appropriate Docker Swarm service
Service returns response

Session Management:

Cookie Configuration:

Domain: Set to specific subdomain (e.g., .member.sas.assemble.com)
Secure flag: Always true (HTTPS only)
HttpOnly flag: True (prevent XSS)
SameSite: Lax or Strict

Token Storage:

JWT tokens stored in localStorage or secure cookies
Tokens scoped to subdomain
Refresh tokens with longer expiry
Token revocation on logout

Cross-Origin Requests:

All portals call api.sas.assemble.com
CORS headers configured in Django
Allowed origins: All portal subdomains
Credentials included in requests

Deployment Strategy:

Each portal deployed as separate Docker service:

sas_admin_portal - Admin portal service
sas_member_portal - Member portal service
sas_provider_portal - Provider portal service
sas_agent_portal - Agent portal service
sas_bi_dashboard - BI dashboard service

Service Configuration:

Each service: 2-5 replicas (based on traffic)
Health checks on /health endpoint
Rolling updates with zero downtime
Auto-scaling based on CPU/memory

4.2 Core API (Django)

Single Django project containing all business modules as Django apps.

The Core API is built in a modular architecture, where each Django app represents a bounded context with clear responsibilities. All modules share a common Django project but maintain loose coupling through well-defined interfaces and dependencies.

Module Overview

App/Module	Responsibility	Key Entities
`authentication`	User auth, roles, permissions, AD integration	User, Role, Permission, Session
`membership`	Member enrollment, profiles, biometric data	Member, Policy, Beneficiary, BiometricRecord
`sales`	Lead management, policy sales, quotations	Lead, Policy, Quote, Contract
`underwriting`	Risk assessment, pricing, quote generation	UnderwritingCase, RiskAssessment, PricingRule
`claims`	Claims submission, adjudication, payment	Claim, ClaimDocument, Adjudication
`finance`	Billing, payments, reconciliation	Invoice, Payment, Transaction
`pnm`	Provider network management	Provider, Credential, Contract
`customer_service`	Support tickets, inquiries	Ticket, Inquiry, Complaint
`wellness`	Wellness programs, health content	Program, Screening, Reward
`reporting`	Report generation, analytics	Report, Schedule, Export
`crm`	Customer engagement, agents, chatbot	Engagement, Agent, Campaign, Contact
`re-insuranse`	Treaty Configuration, Generating Premium Bordereaux and Claims Bordereaux	ReInsuranceTreaty, Bordereaux
`core`	Shared utilities, base models	AuditLog, Notification, Document

API Design Guidelines

All modules expose RESTful APIs following these standardized patterns and conventions.

Base URL Structure

Base URL: https://api.sas.assemble.com/api/v1/

Versioning Strategy:

Version in URL path: /api/v1/, /api/v2/
Maintain backward compatibility within major version
Deprecate old versions with advance notice

API Endpoint Patterns

Standard CRUD Operations:

GET /{resource}/ - List all resources (with pagination)
POST /{resource}/ - Create new resource
GET /{resource}/{id}/ - Get specific resource by ID
PUT /{resource}/{id}/ - Update entire resource
PATCH /{resource}/{id}/ - Partial update of resource
DELETE /{resource}/{id}/ - Delete resource (soft delete preferred)

Action-based Endpoints (for operations beyond CRUD):

POST /{resource}/{id}/{action}/ - Perform action on resource
Examples: /claims/{id}/approve/, /members/{id}/enroll/, /quotes/{id}/generate-pdf/

Nested Resources:

GET /{parent}/{parent_id}/{child}/ - Get child resources of parent
Examples: /members/{id}/policies/, /claims/{id}/documents/

Response Format Standards

Success Response Structure:

{
  "success": true,
  "data": { /* response payload */ },
  "message": "Operation completed successfully",
  "timestamp": "2025-10-13T10:30:00Z"
}

Error Response Structure:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  },
  "timestamp": "2025-10-13T10:30:00Z"
}

Pagination Structure:

{
  "success": true,
  "data": {
    "results": [ /* array of items */ ],
    "count": 150,
    "page": 1,
    "page_size": 20,
    "num_pages": 8,
    "next": "https://api.sas.assemble.com/api/v1/members/?page=2",
    "previous": null
  }
}

HTTP Status Codes

200 OK - Successful GET, PUT, PATCH requests
201 Created - Successful POST request creating new resource
204 No Content - Successful DELETE request
400 Bad Request - Invalid request data
401 Unauthorized - Authentication required or failed
403 Forbidden - Authenticated but not authorized
404 Not Found - Resource not found
409 Conflict - Resource conflict (e.g., duplicate)
422 Unprocessable Entity - Validation error
500 Internal Server Error - Server error
503 Service Unavailable - Service temporarily unavailable

Authentication & Authorization

Request Headers:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
Accept: application/json

Token Management:

Access token: 1 hour expiry
Refresh token: 7 days expiry
Token contains: user ID, roles, permissions

Permission Checks:

Every endpoint validates required permissions
Format: module.action (e.g., claims.approve_claim)
403 Forbidden returned if user lacks permission

Query Parameters

Filtering:

?field=value - Filter by field value
?field__gte=value - Greater than or equal
?field__lte=value - Less than or equal
?field__contains=value - Contains string
?field__in=val1,val2 - In list of values

Sorting:

?ordering=field - Sort ascending
?ordering=-field - Sort descending
?ordering=field1,-field2 - Multiple sort fields

Pagination:

?page=2 - Page number (default: 1)
?page_size=50 - Items per page (default: 20, max: 100)

Search:

?search=query - Full-text search across relevant fields

Examples:

GET /api/v1/claims/?status=pending&ordering=-created_at&page=1&page_size=20
GET /api/v1/members/?search=john&date_joined__gte=2025-01-01
GET /api/v1/policies/?member_id=123&status__in=active,pending

Field Selection & Expansion

Field Selection (reduce response size):

?fields=id,name,email - Only return specified fields

Field Expansion (reduce API calls):

?expand=member,policy - Include related object details

Example:

GET /api/v1/claims/123/?expand=member,provider

Error Codes

Common error codes across all modules:

AUTHENTICATION_REQUIRED - No authentication token provided
AUTHENTICATION_FAILED - Invalid or expired token
PERMISSION_DENIED - User lacks required permission
RESOURCE_NOT_FOUND - Requested resource doesn't exist
VALIDATION_ERROR - Request data validation failed
DUPLICATE_RESOURCE - Resource with same unique field exists
RESOURCE_CONFLICT - Operation conflicts with current state
RATE_LIMIT_EXCEEDED - Too many requests
INTERNAL_ERROR - Server encountered an error

Rate Limiting

Limits by User Type:

Internal users (staff): 1000 requests/minute
External users (members, providers): 100 requests/minute
Anonymous requests: 10 requests/minute

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1697123456

4.2.1 Authentication Module

4.2.1.1 Short Description

The authentication module manages user authentication, authorization, role-based access control (RBAC), and integration with Active Directory for internal users. It provides a unified authentication layer for all portals and handles session management, password policies, and security auditing.

4.2.1.2 Users and Roles

Internal Users (Active Directory):

Admin: Full system access, user management, system configuration
Underwriter: Policy review, risk assessment, pricing approval
Claims Processor: Claims adjudication, payment authorization
Finance Officer: Financial reports, billing, reconciliation
Customer Service Rep: Member support, inquiry resolution

External Users (Database Authentication):

Member: Self-service portal access, policy viewing, claim submission
Provider: Eligibility checks, claim submission, payment history
Agent: Lead management, policy sales, commission tracking

System Roles:

Super Admin: System-wide administrative privileges
API User: Service-to-service authentication

4.2.1.3 Dependency Graph

4.2.1.4 High-level Flow Diagram

4.2.1.5 Features List

User Authentication
- Email/password authentication for external users
- Active Directory (LDAP) integration for internal users
- SSO support via OAuth2/OpenID Connect
- Multi-factor authentication (MFA)
- Biometric authentication support (fingerprint, facial recognition)
Authorization & RBAC
- Role-based access control with granular permissions
- Permission inheritance and grouping
- Dynamic permission evaluation
- Object-level permissions
- Permission caching for performance
Session Management
- Secure session creation and validation
- Session timeout configuration
- Concurrent session limits
- Force logout capability
- Session activity tracking
Password Management
- Password complexity requirements
- Password history tracking
- Password expiration policies
- Self-service password reset
- Temporary password generation
Security Features
- Account lockout after failed attempts
- IP-based access restrictions
- Login attempt rate limiting
- Security question challenges
- Audit trail for all authentication events
Token Management
- JWT token generation and validation
- Refresh token mechanism
- Token revocation list
- Token expiry management
- API key generation for service accounts

4.2.1.6 User Journey

Internal User (Admin) Login Journey:

Admin navigates to admin.sas.assemble.com
System detects internal portal and shows SSO login page
Admin enters corporate email and password
System queries Active Directory via LDAP
AD validates credentials and returns user groups
System maps AD groups to internal roles and permissions
JWT token generated with embedded permissions
Session created in database with expiry timestamp
Authentication event logged to audit trail
Admin redirected to dashboard with appropriate menu items based on role

External User (Member) Login Journey:

Member navigates to member.sas.assemble.com
System shows standard login form (email/password)
Member enters email and password
System queries User table in database
Password hash verified using bcrypt
System loads member's active policies and profile
JWT token generated with member ID and policy info
Session created with member-specific context
Login event logged
Member redirected to policy dashboard showing active policies and claims

Password Reset Journey:

User clicks "Forgot Password" link
Enters email address
System generates secure reset token (valid for 1 hour)
Reset link sent via email
User clicks link and enters new password
System validates token and password complexity
Password hash updated in database
All existing sessions invalidated
User redirected to login page
Confirmation email sent

4.2.1.7 Database Design

4.2.1.8 Exposed APIs

Authentication Endpoints:

POST   /api/v1/auth/login
POST   /api/v1/auth/logout
POST   /api/v1/auth/refresh
POST   /api/v1/auth/verify-token
POST   /api/v1/auth/forgot-password
POST   /api/v1/auth/reset-password
POST   /api/v1/auth/change-password
POST   /api/v1/auth/verify-email
POST   /api/v1/auth/resend-verification

User Management Endpoints:

GET    /api/v1/users
GET    /api/v1/users/{id}
POST   /api/v1/users
PUT    /api/v1/users/{id}
DELETE /api/v1/users/{id}
GET    /api/v1/users/{id}/roles
POST   /api/v1/users/{id}/roles
DELETE /api/v1/users/{id}/roles/{role_id}
GET    /api/v1/users/{id}/permissions
POST   /api/v1/users/{id}/lock
POST   /api/v1/users/{id}/unlock

Role & Permission Endpoints:

GET    /api/v1/roles
GET    /api/v1/roles/{id}
POST   /api/v1/roles
PUT    /api/v1/roles/{id}
DELETE /api/v1/roles/{id}
GET    /api/v1/roles/{id}/permissions
POST   /api/v1/roles/{id}/permissions
DELETE /api/v1/roles/{id}/permissions/{permission_id}

GET    /api/v1/permissions
GET    /api/v1/permissions/{id}
POST   /api/v1/permissions
PUT    /api/v1/permissions/{id}
DELETE /api/v1/permissions/{id}

Session Management Endpoints:

GET    /api/v1/sessions
GET    /api/v1/sessions/{id}
DELETE /api/v1/sessions/{id}
POST   /api/v1/sessions/{id}/revoke
GET    /api/v1/sessions/active
DELETE /api/v1/sessions/revoke-all

Audit & Security Endpoints:

GET    /api/v1/audit/login-attempts
GET    /api/v1/audit/authentication-events
GET    /api/v1/audit/permission-changes
GET    /api/v1/security/password-policy
POST   /api/v1/security/mfa/enable
POST   /api/v1/security/mfa/verify
POST   /api/v1/security/mfa/disable

4.2.2 Membership Module

4.2.2.1 Short Description

The membership module manages the complete lifecycle of insurance members, from enrollment to policy management, beneficiary administration, and biometric data handling. It serves as the central repository for member demographics, policy information, and relationships.

4.2.2.2 Users and Roles

Primary Users:

Admin: Full member data access, enrollment, policy assignment
Customer Service Rep: Member profile updates, inquiry resolution
Underwriter: Policy approval, coverage adjustments
Member (Self-service): View profile, update contact info, view policies

Permissions:

membership.view_member: View member details
membership.add_member: Enroll new members
membership.change_member: Update member information
membership.delete_member: Soft delete members
membership.view_policy: View policy details
membership.add_policy: Create new policies
membership.change_policy: Modify policy details
membership.manage_beneficiaries: Add/remove beneficiaries
membership.view_biometric: View biometric records
membership.add_biometric: Register biometric data

4.2.2.3 Dependency Graph

4.2.2.4 High-level Flow Diagram

4.2.2.5 Features List

Member Enrollment
- Individual and family enrollment
- Bulk enrollment via CSV/Excel
- Duplicate detection (by NIN, email, phone)
- Member ID generation (unique, sequential)
- Photo upload and management
- Biometric registration (fingerprint, facial)
- Welcome communication automation
Member Profile Management
- Demographic information (name, DOB, gender, NIN)
- Contact information (email, phone, address)
- Employment details
- Emergency contact information
- Profile photo management
- Document attachments (ID cards, certificates)
- Profile update approval workflow
Policy Management
- Policy assignment to members
- Policy effective and expiry dates
- Coverage details and limits
- Premium information
- Policy document generation
- Policy renewal tracking
- Policy suspension and termination
- Policy transfer between members
Beneficiary Management
- Add/remove beneficiaries
- Relationship tracking (spouse, child, parent)
- Beneficiary percentage allocation
- Beneficiary verification
- Age limit enforcement (e.g., children under 18)
- Principal vs. dependent designation
Biometric Services
- Fingerprint capture and storage
- Facial recognition data
- Biometric verification for claims
- Multiple biometric templates per member
- Biometric quality scoring
- Biometric device integration
Member Card Services
- Digital member card generation
- QR code generation for verification
- Physical card printing queue
- Card replacement requests
- Card activation and deactivation
- Card expiry management
Family & Relationship Management
- Family group creation
- Principal member designation
- Dependent tracking
- Family policy linking
- Family member addition/removal
- Family tree visualization
Member Search & Filtering
- Search by member ID, name, NIN, phone
- Filter by policy status, enrollment date
- Advanced search with multiple criteria
- Export search results
- Saved search templates

4.2.2.6 User Journey

Member Enrollment Journey (Admin):

Admin logs into Admin Portal (admin.sas.assemble.com)
Navigates to "Membership" → "New Enrollment"
Selects enrollment type (Individual/Family)
Fills enrollment form:
- Personal details (name, DOB, gender, NIN)
- Contact information
- Employment details
- Photo upload
System validates NIN uniqueness against existing members
Admin adds beneficiaries (if applicable)
Selects policy plan from available options
Sets policy effective date
Reviews enrollment summary
Submits enrollment
System generates unique Member ID (e.g., MB-2025-00001)
System creates member and policy records
Biometric capture prompt shown (if enabled)
Admin captures fingerprint using connected device
System generates digital member card with QR code
Welcome email sent to member with login credentials
Admin redirected to member profile page

Self-Service Profile Update Journey (Member):

Member logs into Member Portal (member.sas.assemble.com)
Navigates to "My Profile"
Clicks "Edit Profile"
Updates phone number and address
Uploads new profile photo
Submits changes
System validates updates
Changes marked as "Pending Approval" (if approval required)
Notification sent to Customer Service team
Member sees confirmation message
Customer Service Rep reviews and approves changes
Member receives approval notification
Profile updated in system

Beneficiary Addition Journey (Member):

Member logs into Member Portal
Navigates to "My Policies" → "Policy Details"
Clicks "Manage Beneficiaries"
Clicks "Add Beneficiary"
Fills beneficiary form (name, relationship, DOB, percentage)
Uploads beneficiary ID document
Submits request
System validates total beneficiary percentage = 100%
System creates pending beneficiary record
Underwriter receives approval request
Underwriter verifies documentation
Underwriter approves beneficiary
Member receives confirmation
Updated member card generated with new beneficiary info

4.2.2.7 Database Design

4.2.2.8 Exposed APIs

Member Management Endpoints:

GET    /api/v1/members
GET    /api/v1/members/{id}
POST   /api/v1/members
PUT    /api/v1/members/{id}
DELETE /api/v1/members/{id}
PATCH  /api/v1/members/{id}/activate
PATCH  /api/v1/members/{id}/deactivate
GET    /api/v1/members/{id}/profile
PUT    /api/v1/members/{id}/profile
POST   /api/v1/members/{id}/photo
GET    /api/v1/members/search?q={query}
POST   /api/v1/members/bulk-enroll
GET    /api/v1/members/{id}/audit-trail

Policy Management Endpoints:

GET    /api/v1/members/{member_id}/policies
GET    /api/v1/policies/{id}
POST   /api/v1/policies
PUT    /api/v1/policies/{id}
DELETE /api/v1/policies/{id}
PATCH  /api/v1/policies/{id}/suspend
PATCH  /api/v1/policies/{id}/terminate
PATCH  /api/v1/policies/{id}/renew
GET    /api/v1/policies/{id}/coverage
GET    /api/v1/policies/{id}/documents
POST   /api/v1/policies/{id}/documents/generate

Beneficiary Management Endpoints:

GET    /api/v1/members/{member_id}/beneficiaries
GET    /api/v1/beneficiaries/{id}
POST   /api/v1/members/{member_id}/beneficiaries
PUT    /api/v1/beneficiaries/{id}
DELETE /api/v1/beneficiaries/{id}
PATCH  /api/v1/beneficiaries/{id}/approve
PATCH  /api/v1/beneficiaries/{id}/reject

Biometric Endpoints:

GET    /api/v1/members/{member_id}/biometrics
POST   /api/v1/members/{member_id}/biometrics
GET    /api/v1/biometrics/{id}
DELETE /api/v1/biometrics/{id}
POST   /api/v1/biometrics/verify
POST   /api/v1/biometrics/match

Member Card Endpoints:

GET    /api/v1/members/{member_id}/cards
GET    /api/v1/cards/{id}
POST   /api/v1/members/{member_id}/cards/generate
PATCH  /api/v1/cards/{id}/activate
PATCH  /api/v1/cards/{id}/revoke
GET    /api/v1/cards/{id}/qr-code
POST   /api/v1/cards/verify-qr
GET    /api/v1/cards/print-queue

Document Management Endpoints:

GET    /api/v1/members/{member_id}/documents
POST   /api/v1/members/{member_id}/documents
GET    /api/v1/documents/{id}
DELETE /api/v1/documents/{id}
GET    /api/v1/documents/{id}/download

Emergency Contact Endpoints:

GET    /api/v1/members/{member_id}/emergency-contact
POST   /api/v1/members/{member_id}/emergency-contact
PUT    /api/v1/emergency-contacts/{id}
DELETE /api/v1/emergency-contacts/{id}

4.2.3 Sales Module

4.2.3.1 Short Description

The sales module manages the entire sales lifecycle from lead generation to policy conversion. It provides tools for agents and sales teams to track prospects, generate quotations, manage proposals, and close deals. The module integrates with CRM for lead management and with underwriting for quote approval.

4.2.3.2 Users and Roles

Primary Users:

Agent: Lead management, quotation generation, policy sales
Sales Manager: Team oversight, pipeline monitoring, approval workflows
Admin: Sales configuration, commission setup, report generation
Underwriter: Quote review and approval for complex cases

Permissions:

sales.view_lead: View leads and prospects
sales.add_lead: Create new leads
sales.change_lead: Update lead information
sales.delete_lead: Remove leads
sales.view_quote: View quotations
sales.add_quote: Generate quotations
sales.approve_quote: Approve quotations
sales.view_policy: View sold policies
sales.convert_lead: Convert lead to member
sales.view_commission: View commission reports

4.2.3.3 Dependency Graph

4.2.3.4 High-level Flow Diagram

4.2.3.5 Features List

Lead Management
- Lead capture from multiple sources (web forms, referrals, campaigns)
- Lead scoring and qualification
- Lead assignment to agents (manual/automatic)
- Lead status tracking (new, contacted, qualified, quoted, won, lost)
- Lead source attribution
- Duplicate lead detection and merging
- Lead import from CSV/Excel
- Lead follow-up reminders and scheduling
Quotation Generation
- Interactive quotation builder
- Multiple plan comparison
- Coverage customization
- Premium calculation engine
- Add-on/rider selection
- Discount and promotion application
- Quote versioning and history
- Quote expiration management
- PDF quote generation
- Email quote delivery
Proposal Management
- Proposal document generation
- Coverage illustration
- Terms and conditions inclusion
- Proposal tracking and status
- Proposal presentation scheduler
- Proposal revision management
- Electronic signature integration
- Proposal archive
Sales Pipeline
- Visual pipeline with drag-and-drop
- Stage-based workflow (Lead → Qualified → Quoted → Negotiation → Won/Lost)
- Pipeline value calculation
- Win/loss probability tracking
- Conversion rate analytics
- Stage duration monitoring
- Pipeline forecasting
Commission Management
- Commission structure configuration
- Automatic commission calculation
- Tiered commission rates
- Team commission splits
- Commission approval workflow
- Commission statement generation
- Commission payout tracking
- Override and bonus handling
Sales Reporting & Analytics
- Sales performance dashboards
- Agent leaderboards
- Conversion rate analysis
- Sales funnel visualization
- Revenue forecasting
- Lost opportunity analysis
- Average deal size metrics
- Sales cycle duration tracking
Policy Conversion
- One-click lead-to-member conversion
- Automatic member record creation
- Policy activation
- Contract generation
- Welcome kit preparation
- Payment schedule setup
- Integration with membership module
Document Management
- Quote document storage
- Proposal attachments
- Contract templates
- Electronic signature tracking
- Document version control
- Compliance document checklist

4.2.3.6 User Journey

Agent Lead-to-Sale Journey:

Agent logs into Agent Portal (agent.sas.assemble.com)
New lead notification appears (web form submission)
Agent opens lead details page
Reviews lead information: name, contact, coverage interest
Updates lead status to "Contacted"
Schedules callback using calendar integration
Calls lead and qualifies coverage needs
Clicks "Generate Quote"
Selects plan type (Individual/Family)
Chooses coverage level (Bronze/Silver/Gold)
Adds optional riders (dental, vision)
Applies available discounts (early bird, family discount)
System calculates premium in real-time
Reviews quote summary
Clicks "Generate PDF"
System generates branded quote document
Emails quote to lead with tracking link
Lead opens email (agent gets notification)
Agent follows up via phone
Lead agrees to proceed
Agent clicks "Convert to Member"
System pre-fills enrollment form with lead data
Agent completes additional required fields
Reviews and submits conversion
System creates member record and policy
Commission calculated and assigned to agent
Contract generated and sent to member
Agent receives "Sale Complete" confirmation
Lead moved to "Won" status

Sales Manager Approval Journey:

Sales Manager receives notification: "High-value quote pending approval"
Logs into Admin Portal
Navigates to "Sales" → "Pending Approvals"
Reviews quote details: coverage amount TZS 5,000,000
Checks agent notes and justification
Reviews lead interaction history
Verifies pricing accuracy
Approves quote
System notifies agent
Agent proceeds to present approved quote to lead

Bulk Lead Import Journey (Sales Manager):

Sales Manager receives lead list from marketing campaign (Excel file)
Logs into Admin Portal
Navigates to "Sales" → "Lead Import"
Uploads Excel file (100 leads)
System validates file format and data
Mapping screen shows: Column A → First Name, Column B → Last Name, etc.
Manager confirms mapping
System checks for duplicates (finds 5)
Manager reviews duplicates and selects action (skip/update)
Clicks "Import"
System creates 95 new leads
Auto-assignment rules distribute leads to agents
Agents receive notifications of new assignments
Import summary displayed: 95 created, 5 skipped

4.2.3.7 Database Design

4.2.3.8 Exposed APIs

Lead Management Endpoints:

GET    /api/v1/leads
GET    /api/v1/leads/{id}
POST   /api/v1/leads
PUT    /api/v1/leads/{id}
DELETE /api/v1/leads/{id}
PATCH  /api/v1/leads/{id}/status
POST   /api/v1/leads/{id}/assign
GET    /api/v1/leads/{id}/activities
POST   /api/v1/leads/{id}/activities
GET    /api/v1/leads/my-leads
POST   /api/v1/leads/bulk-import
POST   /api/v1/leads/{id}/convert
GET    /api/v1/leads/search?q={query}
GET    /api/v1/leads/pipeline

Quote Management Endpoints:

GET    /api/v1/quotes
GET    /api/v1/quotes/{id}
POST   /api/v1/quotes
PUT    /api/v1/quotes/{id}
DELETE /api/v1/quotes/{id}
POST   /api/v1/quotes/{id}/calculate
POST   /api/v1/quotes/{id}/generate-pdf
POST   /api/v1/quotes/{id}/send-email
PATCH  /api/v1/quotes/{id}/approve
PATCH  /api/v1/quotes/{id}/reject
PATCH  /api/v1/quotes/{id}/accept
GET    /api/v1/quotes/{id}/versions
POST   /api/v1/quotes/{id}/duplicate
GET    /api/v1/leads/{lead_id}/quotes

Quote Line Item Endpoints:

GET    /api/v1/quotes/{quote_id}/line-items
POST   /api/v1/quotes/{quote_id}/line-items
PUT    /api/v1/quote-line-items/{id}
DELETE /api/v1/quote-line-items/{id}

Agent Management Endpoints:

GET    /api/v1/agents
GET    /api/v1/agents/{id}
POST   /api/v1/agents
PUT    /api/v1/agents/{id}
DELETE /api/v1/agents/{id}
GET    /api/v1/agents/{id}/leads
GET    /api/v1/agents/{id}/performance
GET    /api/v1/agents/{id}/commissions
PATCH  /api/v1/agents/{id}/activate
PATCH  /api/v1/agents/{id}/deactivate

Commission Endpoints:

GET    /api/v1/commissions
GET    /api/v1/commissions/{id}
GET    /api/v1/commissions/pending
POST   /api/v1/commissions/{id}/approve
POST   /api/v1/commissions/{id}/pay
GET    /api/v1/agents/{agent_id}/commissions
GET    /api/v1/commissions/statements
POST   /api/v1/commissions/calculate-batch

Sales Analytics Endpoints:

GET    /api/v1/sales/dashboard
GET    /api/v1/sales/pipeline-summary
GET    /api/v1/sales/conversion-rates
GET    /api/v1/sales/leaderboard
GET    /api/v1/sales/forecast
GET    /api/v1/sales/funnel
GET    /api/v1/sales/lost-opportunities
GET    /api/v1/sales/performance?agent_id={id}&period={period}

Document Endpoints:

GET    /api/v1/quotes/{quote_id}/documents
POST   /api/v1/quotes/{quote_id}/documents
GET    /api/v1/documents/{id}
DELETE /api/v1/documents/{id}
GET    /api/v1/documents/{id}/download
POST   /api/v1/documents/{id}/send
GET    /api/v1/documents/{id}/tracking

4.2.4 Underwriting Module

4.2.4.1 Short Description

The underwriting module handles risk assessment, policy pricing, and approval workflows for insurance applications. It manages underwriting rules, medical evaluations, risk scoring, and pricing calculations. The module ensures that all policies are properly assessed for risk before approval and that premiums are calculated accurately based on risk factors.

4.2.4.2 Users and Roles

Primary Users:

Underwriter: Risk assessment, application review, policy approval/rejection
Senior Underwriter: Complex case review, high-value policy approval, rule configuration
Medical Examiner: Medical report review, health assessment
Admin: Underwriting rule management, pricing configuration, report generation

Permissions:

underwriting.view_case: View underwriting cases
underwriting.add_case: Create underwriting cases
underwriting.change_case: Update case information
underwriting.approve_case: Approve underwriting cases
underwriting.reject_case: Reject underwriting cases
underwriting.view_pricing: View pricing rules
underwriting.change_pricing: Modify pricing rules
underwriting.view_risk_assessment: View risk assessments
underwriting.override_decision: Override automated decisions

4.2.4.3 Dependency Graph

4.2.4.4 High-level Flow Diagram

4.2.4.5 Features List

Case Management
- Automatic case creation from quotes/applications
- Case assignment to underwriters (manual/automatic)
- Case status tracking (pending, in_review, approved, rejected)
- Case priority management (standard, urgent, high-value)
- Case notes and comments
- Case history and audit trail
- Case search and filtering
- Case workload balancing
Risk Assessment
- Automated risk scoring algorithms
- Multi-factor risk evaluation (age, health, occupation, lifestyle)
- Medical history analysis
- Pre-existing condition identification
- Risk category classification (low, medium, high)
- Risk factor weighting
- Historical claims data analysis
- Predictive risk modeling
Medical Underwriting
- Medical questionnaire management
- Medical exam scheduling
- Medical report upload and review
- Doctor/examiner network integration
- Medical condition database
- BMI and health metric calculations
- Blood test result evaluation
- Medical history verification
Underwriting Rules Engine
- Configurable business rules
- Rule-based decision automation
- Age and sum assured thresholds
- Occupation risk tables
- Lifestyle factor rules (smoking, alcohol)
- Geographic risk considerations
- Auto-approval criteria
- Automatic referral rules
- Rule version control
Pricing & Premium Calculation
- Base premium calculation
- Risk-based premium loading
- Discount application
- Age-based rating
- Sum assured scaling
- Loading for pre-existing conditions
- Premium rounding rules
- Multi-year premium projection
- Re-rating on renewal
Decision Management
- Approve/reject workflow
- Conditional approval (with exclusions/loadings)
- Counter-offer generation
- Decline reason tracking
- Decision appeal process
- Override and exception handling
- Senior underwriter escalation
- Decision templates
Document Management
- Application form storage
- Medical report management
- ID verification documents
- Income proof documents
- Underwriting decision letters
- Policy exclusion documentation
- Document checklist management
- Document OCR and extraction
Reporting & Analytics
- Underwriting productivity reports
- Approval/rejection rate analysis
- Average turnaround time tracking
- Risk profile distribution
- Premium adequacy analysis
- Underwriter performance metrics
- Case aging reports
- Referral pattern analysis

4.2.4.6 User Journey

Auto-underwriting Journey (Low Risk Applicant):

Quote accepted by lead in sales module
System automatically creates underwriting case
Case assigned to "Auto-underwriting" queue
System extracts applicant data:
- Age: 28 years
- Sum Assured: TZS 1,000,000
- Occupation: Software Engineer (low-risk)
- Non-smoker
- No pre-existing conditions declared
Automated rules engine evaluates case
Risk score calculated: 85/100 (Low Risk)
Premium calculated: TZS 15,000/year
System auto-approves case (within auto-approval limits)
Case status changed to "Approved"
Notification sent to sales agent
Member enrollment proceeds automatically
Policy documents generated

Manual Underwriting Journey (Medium Risk Applicant):

Application received for TZS 5,000,000 coverage
System creates underwriting case
Initial risk scoring: Medium Risk (BMI 32, age 45)
Case automatically assigned to Underwriter (John)
John receives notification and opens case
Reviews applicant information:
- Medical questionnaire shows hypertension (controlled)
- Occupation: Construction Manager (medium-risk)
- Family history of diabetes
John requests medical exam
System sends exam request to medical network
Medical exam scheduled at approved clinic
Exam completed, results uploaded to system
John reviews medical report:
- Blood pressure: 140/90 (borderline)
- Cholesterol: Slightly elevated
- Other tests: Normal
John applies underwriting rules
System recommends: Approve with 15% loading
John accepts recommendation
Adjusted premium calculated: TZS 86,250/year (was TZS 75,000)
John approves case with medical loading
Decision letter generated explaining loading
Sales agent notified to present terms to applicant
Applicant accepts adjusted premium
Policy issued with medical loading

Senior Underwriter Review Journey (High Risk Case):

Application received for TZS 10,000,000 coverage
Applicant age: 55, smoker, diabetic
Initial risk score: High Risk
Case assigned to Senior Underwriter (Sarah)
Sarah reviews comprehensive medical reports
Notes history of Type 2 diabetes (10 years)
Recent HbA1c: 7.5% (moderately controlled)
BMI: 29 (overweight)
Sarah considers options:
- Option A: Decline (high risk)
- Option B: Approve with exclusions + loading
- Option C: Reduce coverage amount
Sarah decides: Approve with diabetes exclusion + 40% loading
Terms:
- Coverage: TZS 10,000,000
- Exclusion: Diabetes-related claims
- Loading: 40%
- Premium: TZS 280,000/year (base: TZS 200,000)
Counter-offer generated
Sales agent presents terms to applicant
Applicant accepts terms
Policy issued with documented exclusions

4.2.4.7 Database Design

4.2.4.8 Exposed APIs

Underwriting Case Endpoints:

GET    /api/v1/underwriting/cases
GET    /api/v1/underwriting/cases/{id}
POST   /api/v1/underwriting/cases
PUT    /api/v1/underwriting/cases/{id}
DELETE /api/v1/underwriting/cases/{id}
PATCH  /api/v1/underwriting/cases/{id}/status
POST   /api/v1/underwriting/cases/{id}/assign
GET    /api/v1/underwriting/cases/my-queue
GET    /api/v1/underwriting/cases/pending
GET    /api/v1/underwriting/cases/{id}/timeline
POST   /api/v1/underwriting/cases/{id}/escalate

Risk Assessment Endpoints:

GET    /api/v1/underwriting/cases/{case_id}/risk-assessment
POST   /api/v1/underwriting/cases/{case_id}/risk-assessment
POST   /api/v1/underwriting/risk-assessment/auto-assess
GET    /api/v1/underwriting/risk-factors
POST   /api/v1/underwriting/risk-factors
PUT    /api/v1/underwriting/risk-factors/{id}
DELETE /api/v1/underwriting/risk-factors/{id}

Medical Exam Endpoints:

GET    /api/v1/underwriting/cases/{case_id}/medical-exams
POST   /api/v1/underwriting/cases/{case_id}/medical-exams
GET    /api/v1/underwriting/medical-exams/{id}
PUT    /api/v1/underwriting/medical-exams/{id}
PATCH  /api/v1/underwriting/medical-exams/{id}/schedule
PATCH  /api/v1/underwriting/medical-exams/{id}/complete
POST   /api/v1/underwriting/medical-exams/{id}/upload-report

Decision Management Endpoints:

GET    /api/v1/underwriting/cases/{case_id}/decision
POST   /api/v1/underwriting/cases/{case_id}/approve
POST   /api/v1/underwriting/cases/{case_id}/reject
POST   /api/v1/underwriting/cases/{case_id}/counter-offer
POST   /api/v1/underwriting/decisions/{id}/senior-approval
GET    /api/v1/underwriting/decisions/pending-approval

Pricing & Rules Endpoints:

POST   /api/v1/underwriting/calculate-premium
GET    /api/v1/underwriting/pricing-rules
GET    /api/v1/underwriting/pricing-rules/{id}
POST   /api/v1/underwriting/pricing-rules
PUT    /api/v1/underwriting/pricing-rules/{id}
DELETE /api/v1/underwriting/pricing-rules/{id}
POST   /api/v1/underwriting/pricing-rules/{id}/test
GET    /api/v1/underwriting/pricing-rules/{id}/conditions
POST   /api/v1/underwriting/pricing-rules/{id}/conditions

Document Management Endpoints:

GET    /api/v1/underwriting/cases/{case_id}/documents
POST   /api/v1/underwriting/cases/{case_id}/documents
GET    /api/v1/underwriting/documents/{id}
DELETE /api/v1/underwriting/documents/{id}
GET    /api/v1/underwriting/documents/{id}/download
PATCH  /api/v1/underwriting/documents/{id}/verify
POST   /api/v1/underwriting/documents/ocr-extract

Case Notes Endpoints:

GET    /api/v1/underwriting/cases/{case_id}/notes
POST   /api/v1/underwriting/cases/{case_id}/notes
GET    /api/v1/underwriting/notes/{id}
PUT    /api/v1/underwriting/notes/{id}
DELETE /api/v1/underwriting/notes/{id}

Reporting & Analytics Endpoints:

GET    /api/v1/underwriting/reports/dashboard
GET    /api/v1/underwriting/reports/productivity
GET    /api/v1/underwriting/reports/approval-rates
GET    /api/v1/underwriting/reports/turnaround-time
GET    /api/v1/underwriting/reports/risk-distribution
GET    /api/v1/underwriting/reports/case-aging
GET    /api/v1/underwriting/reports/underwriter-performance
GET    /api/v1/underwriting/analytics/trends

4.2.5 Claims Module

4.2.5.1 Short Description

The claims module manages the entire claims lifecycle from submission to payment. It handles claim registration, document management, adjudication workflows, fraud detection, and payment processing. The module integrates with AI/ML services for automated claim assessment and fraud detection, and with the finance module for payment disbursement.

4.2.5.2 Users and Roles

Primary Users:

Member: Claim submission, status tracking, document upload
Provider: Provider-initiated claims, pre-authorization requests
Claims Processor: Claim review, adjudication, approval/denial
Claims Manager: Complex case review, approval workflow, analytics
Finance Officer: Payment verification and processing
Fraud Investigator: Fraud case investigation and resolution

Permissions:

claims.view_claim: View claim details
claims.add_claim: Submit new claims
claims.change_claim: Update claim information
claims.approve_claim: Approve claims for payment
claims.reject_claim: Reject/deny claims
claims.process_payment: Process claim payments
claims.view_fraud_alert: View fraud detection alerts
claims.investigate_fraud: Investigate fraud cases

4.2.5.3 Dependency Graph

4.2.5.4 High-level Flow Diagram

4.2.5.5 Features List

Claim Submission
- Member-initiated claims (via portal/mobile app)
- Provider-initiated claims
- Bulk claim upload (for providers)
- Multiple claim types (inpatient, outpatient, pharmacy, dental, optical)
- Pre-authorization request workflow
- Emergency claim fast-track
- Claim number generation
- Duplicate claim detection
Document Management
- Medical invoice upload
- Prescription document upload
- Lab/test result upload
- Hospital discharge summary
- Provider invoice attachment
- Document type validation
- OCR for invoice data extraction
- Document verification workflow
- Document quality checks
Claim Adjudication
- Automated eligibility verification
- Coverage validation against policy
- Benefit limit checking
- Service code validation (ICD-10, CPT)
- Pricing validation against provider contracts
- Duplicate service detection
- Bundled service detection
- Medically necessary service validation
- Claims processor assignment
AI-Powered Assessment
- LLM-based claim document analysis
- Automated claim validity scoring
- Medical necessity determination
- Document completeness check
- Anomaly detection
- Diagnosis-procedure match verification
- Historical pattern analysis
- Approval recommendation generation
Fraud Detection
- AI/ML fraud risk scoring
- Pattern-based fraud detection
- Provider fraud patterns
- Member fraud patterns
- Duplicate claim identification
- Upcoding detection
- Phantom billing detection
- Unbundling detection
- Frequency abuse detection
- Fraud case management
Payment Processing
- Payment amount calculation
- Deductible application
- Copayment deduction
- Coinsurance calculation
- Maximum benefit enforcement
- Multi-level approval workflow
- Payment batch generation
- Payment to provider or member
- Payment reconciliation
- Payment status tracking
Communication & Notifications
- Claim status SMS/email notifications
- Document request notifications
- Approval/rejection notifications
- Payment confirmation
- Provider payment notifications
- Automated status updates
- In-app notification center
- Claim timeline visibility
Reporting & Analytics
- Claims dashboard (volume, value, status)
- Turnaround time analysis
- Approval/rejection rate tracking
- Claims cost analysis
- Provider performance analysis
- Fraud detection metrics
- Loss ratio calculation
- Claims aging reports
- Processor productivity reports

4.2.5.6 User Journey

Member Self-Service Claim Submission Journey:

Member logs into Member Portal (member.sas.assemble.com)
Navigates to "Claims" → "Submit New Claim"
Selects claim type: "Outpatient"
System displays active policy with coverage details
Enters claim details:
- Date of service: 2025-10-10
- Provider: ABC Medical Center
- Diagnosis: Malaria
- Treatment received: Consultation + Lab test + Medication
Enters claim amount: TZS 25,000
Uploads documents:
- Medical invoice (PDF)
- Lab test results (PDF)
- Pharmacy receipt (image)
System validates documents (format, size, readability)
OCR extracts invoice data automatically
Reviews extracted data and confirms accuracy
Submits claim
System generates Claim ID: CLM-2025-00123
Fraud detection AI runs in background (score: 0.15 - Low Risk)
Eligibility checked: Policy active, Outpatient covered
Claim assigned to auto-adjudication queue
AI/LLM analyzes documents:
- Invoice matches lab results
- Diagnosis appropriate for services
- Pricing within normal range
AI recommends: Approve TZS 23,500 (after TZS 1,500 copay)
System auto-approves (amount under TZS 50,000 threshold)
Member receives SMS: "Your claim CLM-2025-00123 has been approved. TZS 23,500 will be paid within 3 business days."
Finance module processes payment to member's bank account
Member receives payment notification
Claim status updated to "Paid" in portal

Claims Processor Manual Review Journey:

Claims Processor (Jane) logs into Admin Portal
Navigates to "Claims" → "My Queue"
Sees claim CLM-2025-00456 flagged for manual review
Opens claim details:
- Member: John Doe (Policy: POL-2024-00789)
- Claim type: Inpatient
- Amount: TZS 850,000 (surgical procedure)
- Reason for manual review: High amount + complex surgery
Reviews uploaded documents:
- Hospital discharge summary
- Surgical operation notes
- Itemized hospital bill
- Lab/imaging reports
Verifies policy coverage:
- Surgery type: Covered
- Maximum limit: TZS 2,000,000 (annual)
- Already used: TZS 300,000
- Available: TZS 1,700,000
Validates service codes against ICD-10 database
Checks provider contract pricing
Notes hospital charged TZS 850,000, contract price TZS 780,000
Adjusts approved amount to TZS 780,000
Calculates payment: TZS 780,000 - TZS 50,000 (deductible) = TZS 730,000
Amount requires manager approval (> TZS 500,000)
Adds notes and submits for manager review
Claims Manager (Mike) receives notification
Mike reviews case and approves
System updates claim status to "Approved - Pending Payment"
Finance Officer reviews and processes payment to hospital
Hospital receives payment notification with remittance advice
Member receives notification: "Claim approved, payment sent to hospital"
Claim closed

Fraud Investigation Journey:

System flags claim CLM-2025-00789 with high fraud score (0.92)
Fraud alert triggers:
- Same member submitted 5 claims in 2 weeks
- All claims from different providers
- Similar diagnosis codes
- Suspicious pricing patterns
Claim automatically suspended
Fraud Investigator (Sarah) assigned to case
Sarah reviews member's claim history:
- 8 claims in 1 month (normal average: 1-2/year)
- All outpatient claims
- Total claimed: TZS 450,000
Checks provider patterns:
- 2 providers appear in multiple suspicious claims
- Providers flagged by system before
Sarah contacts member via phone (no answer)
Sarah requests additional verification:
- Original invoices (not photocopies)
- Provider verification call
Contacts providers directly:
- Provider A: No record of member visit
- Provider B: Confirms visit but amount inflated
Sarah confirms fraud
Rejects all 5 recent claims
Flags member account for monitoring
Reports providers to regulatory body
Documents investigation findings
Member notified of rejection with fraud suspicion
Case marked as "Closed - Fraud Confirmed"

4.2.5.7 Database Design

4.2.5.8 Exposed APIs

Claim Management Endpoints:

GET    /api/v1/claims
GET    /api/v1/claims/{id}
POST   /api/v1/claims
PUT    /api/v1/claims/{id}
DELETE /api/v1/claims/{id}
GET    /api/v1/claims/{id}/timeline
PATCH  /api/v1/claims/{id}/status
POST   /api/v1/claims/{id}/assign
GET    /api/v1/claims/my-claims
GET    /api/v1/claims/queue
POST   /api/v1/claims/{id}/suspend
POST   /api/v1/claims/{id}/resume

Claim Line Item Endpoints:

GET    /api/v1/claims/{claim_id}/line-items
POST   /api/v1/claims/{claim_id}/line-items
PUT    /api/v1/claim-line-items/{id}
DELETE /api/v1/claim-line-items/{id}

Document Management Endpoints:

GET    /api/v1/claims/{claim_id}/documents
POST   /api/v1/claims/{claim_id}/documents
GET    /api/v1/claim-documents/{id}
DELETE /api/v1/claim-documents/{id}
GET    /api/v1/claim-documents/{id}/download
POST   /api/v1/claim-documents/{id}/verify
POST   /api/v1/claim-documents/ocr-extract

Adjudication Endpoints:

POST   /api/v1/claims/{claim_id}/adjudicate
GET    /api/v1/claims/{claim_id}/adjudication
POST   /api/v1/claims/{claim_id}/auto-adjudicate
POST   /api/v1/adjudications/{id}/decide
POST   /api/v1/adjudications/{id}/approve
POST   /api/v1/adjudications/{id}/reject
POST   /api/v1/adjudications/{id}/request-info
GET    /api/v1/adjudications/pending-decision

Fraud Detection Endpoints:

POST   /api/v1/claims/{claim_id}/fraud-check
GET    /api/v1/claims/{claim_id}/fraud-check
GET    /api/v1/fraud-checks/high-risk
POST   /api/v1/fraud-checks/{id}/investigate
POST   /api/v1/fraud-checks/{id}/clear
POST   /api/v1/fraud-checks/{id}/confirm-fraud
GET    /api/v1/fraud-checks/investigations
GET    /api/v1/fraud-checks/analytics

Payment Processing Endpoints:

GET    /api/v1/claims/{claim_id}/payments
POST   /api/v1/claims/{claim_id}/payments
GET    /api/v1/payments/{id}
POST   /api/v1/payments/{id}/approve
POST   /api/v1/payments/{id}/process
POST   /api/v1/payments/{id}/cancel
GET    /api/v1/payments/pending
GET    /api/v1/payments/batch
POST   /api/v1/payments/batch-process

Pre-authorization Endpoints:

POST   /api/v1/claims/preauth
GET    /api/v1/claims/preauth/{id}
PATCH  /api/v1/claims/preauth/{id}/approve
PATCH  /api/v1/claims/preauth/{id}/reject
GET    /api/v1/claims/preauth/pending

Reporting & Analytics Endpoints:

GET    /api/v1/claims/reports/dashboard
GET    /api/v1/claims/reports/volume-analysis
GET    /api/v1/claims/reports/turnaround-time
GET    /api/v1/claims/reports/approval-rates
GET    /api/v1/claims/reports/cost-analysis
GET    /api/v1/claims/reports/provider-performance
GET    /api/v1/claims/reports/fraud-metrics
GET    /api/v1/claims/reports/loss-ratio
GET    /api/v1/claims/reports/aging
GET    /api/v1/claims/analytics/trends

Eligibility & Coverage Endpoints:

POST   /api/v1/claims/check-eligibility
POST   /api/v1/claims/verify-coverage
POST   /api/v1/claims/check-limits
GET    /api/v1/claims/service-codes
GET    /api/v1/claims/diagnosis-codes

4.3 Celery Worker Pools

Separate worker processes for async/heavy tasks, can scale independently.

4.3.1 Worker Types & Task Queues

Claims Processing Queue:

Process claim submission
Run fraud detection checks
Auto-adjudication with LLM
Generate claim reports

Reports Queue:

Generate PDF reports
Export large datasets
Create dashboards
Scheduled report generation

General Queue:

Send email notifications
Send SMS notifications
Generate member cards
Process bulk operations
Sync with external systems

4.3.2 Task Routing Strategy

Tasks are routed to specific queues based on:

Resource intensity (CPU, memory, I/O)
Priority (high, medium, low)
Expected duration (short, medium, long)
Frequency (rare, common, continuous)

4.3.3 Scaling Strategy

Workers can be scaled independently:

Claims workers: Scale based on claim volume
Reports workers: Scale based on report generation requests
General workers: Scale based on notification volume

4.4 FastAPI AI/ML Service

Separate service for machine learning workloads.

4.4.1 Why Separate?

Different resource requirements: GPU for ML models
Different scaling needs: AI tasks are compute-intensive
Technology optimization: FastAPI + PyTorch optimized for ML
Performance isolation: ML doesn't slow down main Django app

4.4.2 Responsibilities

Fraud Detection:

Real-time fraud scoring for claims
Pattern recognition in transactions
Provider behavior analysis
LLM-based document analysis

Claims Processing:

Auto-adjudication using LLM
Medical coding assistance
Treatment validation

CRM & Engagement:

Chatbot conversational AI (LLM)
Product recommendations
Customer sentiment analysis

Predictive Analytics:

Member churn prediction
Risk scoring for underwriting
Anomaly detection across all modules

4.4.3 Communication Pattern

Django calls FastAPI via REST API for real-time needs
Celery tasks call FastAPI for async processing
FastAPI can write results back to shared PostgreSQL database

5. Technology Stack

5.1 Backend

Component	Technology	Purpose
Web Framework	Django 5.0	Main application framework
API Framework	Django REST Framework	RESTful API endpoints
Task Queue	Celery 5.x	Async task processing
AI/ML Service	FastAPI	ML model serving
Message Broker	Redis	Celery broker + caching

5.2 Frontend

Component	Technology	Purpose
Monorepo Tool	Turborepo	Build system and task runner
Package Manager	pnpm	Fast, efficient dependency management
Admin Portal	React 19 + TypeScript + Vite	Internal staff interface
Member Portal	React 19 + TypeScript + Vite	Member self-service portal
Provider Portal	React 19 + TypeScript + Vite	Healthcare provider interface
Agent Portal	React 19 + TypeScript + Vite	Agent/broker interface
BI Dashboard	React 19 + D3.js/Chart.js	Analytics dashboards
Mobile App	Flutter	iOS and Android apps
API Client	@sas/api-client (Axios)	REST API communication
State Management	Zustand / React Context	Application state
Form Management	React Hook Form	Form validation and handling
Styling	Tailwind CSS / CSS Modules	Consistent design system

5.3 Data Layer

Component	Technology	Purpose
Database	PostgreSQL 17 Cluster	Primary data storage with replication
Cache	Redis 7	Caching + message broker
Object Storage	Local Drive	Document storage
Search	PostgreSQL Full-Text	Search functionality

5.4 Infrastructure

Component	Technology	Purpose
Container Runtime	Docker	Containerization
Orchestration	Docker Swarm	Container orchestration
Load Balancer	Traefik	Traffic distribution
Reverse Proxy	Traefik	SSL termination, static files
Monitoring	Prometheus + Grafana	Metrics and alerting
Logging	Loki	Centralized logging

5.5 External Integrations

Active Directory - Internal user authentication
Banking APIs - Payment processing
Hospital Management Systems - Claims integration
Sage ERP - Financial system integration
SMS Gateway - SMS notifications

6. Database Design

6.1 PostgreSQL Cluster Strategy

Database cluster: sas_production

Master Database: Handles all write operations
Read Replicas: Multiple replicas (Replica 0, Replica 1, Replica N) for read operations
Replication: Streaming replication for high availability

Logical separation via table prefixes: This is well handled by django

auth_* - Authentication tables
membership_* - Membership tables
claims_* - Claims tables
crm_* - CRM tables
finance_* - Finance tables
core_* - Core/shared tables

6.2 Database Schema Organization

Authentication Tables:

auth_user - User accounts
auth_role - User roles
auth_permission - System permissions
auth_session - User sessions

Membership Tables:

membership_member - Member profiles
membership_policy - Policy assignments
membership_beneficiary - Beneficiaries
membership_biometric_record - Biometric data (encrypted)

Claims Tables:

claims_claim - Main claim records
claims_document - Supporting documents
claims_adjudication - Adjudication history
claims_payment - Payment records

CRM Tables:

crm_engagement - Customer engagements
crm_agent - Agent/broker records
crm_campaign - Marketing campaigns
crm_contact - Contact records

Finance Tables:

finance_invoice - Invoices
finance_payment - Payments
finance_transaction - All transactions
finance_reconciliation - Reconciliation records

Core/Shared Tables:

core_audit_log - Audit trail for all modules
core_notification - Notification queue
core_document - Document metadata

6.3 Database Relationships

Foreign Key Strategy:

Use standard Django foreign keys between models
Enable on_delete=PROTECT for critical relationships
Use on_delete=CASCADE carefully (only for dependent data)
Create indexes on foreign key columns

Cross-Module References:

Claims reference Members (membership_member)
Claims reference Providers (pnm_provider)
Finance references Claims (claims_claim)
CRM references Members (membership_member)
All modules reference Users (auth_user)

7. Asynchronous Processing

7.1 Celery Architecture

7.2 Task Queue Strategy

Claims Queue Tasks:

Process claim submission (validate, create record)
Run fraud detection check via AI service
Auto-adjudicate claim using LLM
Generate claim notifications
Update claim status

Reports Queue Tasks:

Generate PDF reports (CPU/memory intensive)
Export large datasets to Excel/CSV
Create dashboard snapshots
Scheduled report generation
Data aggregation for analytics

General Queue Tasks:

Send email notifications (bulk and individual)
Send SMS messages
Generate member cards with QR codes
Process document uploads
Sync data with external systems

7.3 Task Prioritization

High Priority:

Fraud detection (security-critical)
Payment processing
Critical notifications

Medium Priority:

Claim adjudication
Report generation
Data exports

Low Priority:

Bulk notifications
Non-urgent syncs
Cleanup tasks

7.4 Task Retry Strategy

Retry Configuration:

Maximum retries: 3 attempts
Retry delay: Exponential backoff (60s, 120s, 240s)
Failed task handling: Log to error queue for manual review

Idempotency:

All tasks designed to be idempotent
Can safely retry without side effects
Use unique identifiers to prevent duplicates

8. Deployment Architecture

8.1 Docker Swarm Deployment

8.2 Service Distribution

Manager Nodes (3 nodes):

Run Swarm orchestration
Host data services (PostgreSQL Cluster, Redis, Local Storage)
Run monitoring services (Prometheus, Grafana)
Ensure high availability

Worker Nodes (3+ nodes):

Run Frontend portal instances (Admin, Member, Provider, Agent, BI)
Run Traefik load balancer
Run Django application instances
Run Celery workers
Run AI/ML service
Scale horizontally as needed

Frontend Portal Services:

sas_admin_portal - Admin portal replicas (2-3)
sas_member_portal - Member portal replicas (3-5, high traffic)
sas_provider_portal - Provider portal replicas (2-3)
sas_agent_portal - Agent portal replicas (2-3)
sas_bi_dashboard - BI dashboard replicas (1-2, low traffic)
sas_traefik - Load balancer with subdomain routing (2-3 replicas)

8.3 Service Scaling Configuration

Frontend Portals:

Member Portal:

Initial replicas: 3
Minimum replicas: 2
Maximum replicas: 8
Scale trigger: CPU > 70% or Request rate > 1000/s

Admin Portal:

Initial replicas: 2
Minimum replicas: 1
Maximum replicas: 5
Scale trigger: CPU > 70%

Provider Portal:

Initial replicas: 2
Minimum replicas: 1
Maximum replicas: 5
Scale trigger: CPU > 70%

Agent Portal:

Initial replicas: 2
Minimum replicas: 1
Maximum replicas: 5
Scale trigger: CPU > 70%

BI Dashboard:

Initial replicas: 1
Minimum replicas: 1
Maximum replicas: 3
Scale trigger: CPU > 80%

Django Application:

Initial replicas: 3
Minimum replicas: 2
Maximum replicas: 10
Scale trigger: CPU > 70%

Celery Workers - Claims:

Initial replicas: 3
Minimum replicas: 2
Maximum replicas: 10
Scale trigger: Queue depth > 100

Celery Workers - Reports:

Initial replicas: 2
Minimum replicas: 1
Maximum replicas: 5
Scale trigger: Queue depth > 50

Celery Workers - General:

Initial replicas: 2
Minimum replicas: 1
Maximum replicas: 5
Scale trigger: Queue depth > 100

AI/ML Service:

Initial replicas: 2
Minimum replicas: 1
Maximum replicas: 5
Scale trigger: CPU > 80% or Queue depth

8.4 Resource Allocation

Frontend Portal Containers:

CPU: 0.5-1 core (static serving)
Memory: 512 MB - 1 GB
Storage: 500 MB (built static files)

Django Container:

CPU: 1-2 cores
Memory: 2-4 GB
Storage: 10 GB

Celery Worker Container:

CPU: 1-2 cores
Memory: 2-4 GB
Storage: 10 GB

AI/ML Container:

CPU: 2-4 cores (or 1 GPU)
Memory: 4-8 GB
Storage: 20 GB (for models)

PostgreSQL Master Container:

CPU: 4 cores
Memory: 8 GB
Storage: 500 GB (SSD)

PostgreSQL Replica Container:

CPU: 2-4 cores
Memory: 8 GB
Storage: 500 GB (SSD)

Redis Container:

CPU: 2 cores
Memory: 4 GB
Storage: 20 GB

8.5 Health Checks

Django Health Check:

Endpoint: /health/
Checks: Database connection, Redis connection
Interval: 30 seconds
Timeout: 10 seconds

Celery Worker Health:

Check: Worker process running
Check: Can connect to Redis broker
Check: Can connect to database
Interval: 60 seconds

AI/ML Service Health:

Endpoint: /health/
Checks: Model loaded, GPU available (if applicable)
Interval: 30 seconds

9. Scaling Strategy

9.1 When to Scale

Django Instances:

Metric	Threshold	Action
CPU Usage	> 70%	Scale up Django replicas
Memory Usage	> 80%	Scale up Django replicas
Request Queue	> 100	Scale up Django replicas
Response Time	> 500ms	Scale up Django replicas

Celery Workers:

Metric	Threshold	Action
Claims Queue Depth	> 100	Scale claims workers
Reports Queue Depth	> 50	Scale reports workers
General Queue Depth	> 100	Scale general workers
Task Wait Time	> 5 min	Scale appropriate workers

Database Cluster:

Metric	Threshold	Action
Master Connection Count	> 80% max	Add connection pooling
Master CPU Usage	> 80%	Optimize queries or add replicas
Master Disk I/O	> 80%	Add more read replicas
Replica Lag	> 5 seconds	Investigate network/disk issues
Storage	> 80%	Expand storage on all nodes

9.2 Horizontal Scaling Commands

Scale Django:

docker service scale sas_django=5

Scale Celery Workers:

docker service scale sas_celery_claims=10
docker service scale sas_celery_reports=5
docker service scale sas_celery_general=3

Scale AI/ML Service:

docker service scale sas_ai=5

9.3 Vertical Scaling

When to Consider:

Master database performance bottleneck
Redis memory constraints
All horizontal scaling exhausted

Options:

Upgrade server hardware (CPU, RAM, SSD)
Add more read replicas to database cluster
Implement Redis cluster
Optimize application code and queries

9.4 Load Distribution

Nginx Load Balancing:

Algorithm: Least connections
Health checks: Every 30 seconds
Automatic removal of unhealthy instances
Session persistence via cookies

Database Cluster Load:

Write operations: Master database only
Read operations: Distributed across read replicas
Connection pooling: PgBouncer for all connections
Replica routing: Automatic failover on replica failure

10. Integration Patterns

10.1 External System Integration Strategy

Integration Approaches:

REST API Integration: For real-time data exchange
Webhook Integration: For event-driven updates
Batch/Scheduled Sync: For bulk data transfers
Message Queue: For reliable async communication

10.2 Active Directory Integration

Purpose: Authenticate internal staff users

Integration Type: LDAP over SSL

Data Sync:

User credentials: Validated real-time
User attributes: Synced on login
Group membership: Mapped to Django roles

10.3 Banking System Integration

Purpose: Process payments and transfers

Integration Type: REST API + Webhooks

Workflows:

Initiate payment for claims
Process premium payments
Check payment status
Receive payment confirmations via webhook

Security:

API key authentication
TLS encryption
Request signing for sensitive operations
IP whitelisting

10.4 Hospital Management System (HMS) Integration

Purpose: Claims submission and eligibility checks

Integration Type: REST API or SOAP

Data Exchange Format:

Preferred: HL7 FHIR
Legacy: Custom JSON/XML

Workflows:

Check member eligibility at provider
Submit claims electronically
Receive adjudication results
Update claim status

10.5 Sage ERP Integration

Purpose: Financial data synchronization

Integration Type: REST API + Scheduled Batch

Workflows:

Export invoices daily
Export payments daily
Export GL entries
Generate reconciliation reports

Sync Schedule:

Daily: Invoices, payments, transactions
Weekly: Reconciliation reports
Monthly: Financial statements

10.6 SMS/Email Gateway Integration

Purpose: Send notifications to users

Integration Type: REST API

Use Cases:

Policy purchase confirmations
Claim status updates
Payment reminders
Appointment reminders
Marketing campaigns

Providers:

Local SMS gateway providers

11. Performance Optimization

11.1 Caching Strategy

Cache Layers:

Redis Cache: Application-level caching
Database Query Cache: Frequent queries
HTTP Response Cache: API responses

What to Cache:

User sessions and authentication tokens
Frequently accessed reference data (providers, products)
Computed values (reports, statistics)
API responses for read-heavy endpoints

Cache Invalidation:

Time-based: TTL for each cache entry
Event-based: Invalidate on data changes
Manual: Admin tools to clear cache

11.2 Database Optimization

Query Optimization:

Use select_related() for foreign keys
Use prefetch_related() for many-to-many
Add indexes on frequently queried columns
Avoid N+1 queries

Connection Management:

Use connection pooling (PgBouncer)
Configure max connections appropriately
Close idle connections

Read Replicas:

Route read queries to replicas (Replica 0, Replica 1, Replica N)
Keep writes on master only
Use for reports and analytics
Load balance reads across multiple replicas

11.3 API Performance

Response Time Targets:

Simple GET requests: < 100ms
Complex queries: < 500ms
Write operations: < 1s
Long operations: Async via Celery

Optimization Techniques:

Pagination for large result sets
Field filtering (only return requested fields)
Compression for large responses
Rate limiting to prevent abuse

12. Monitoring & Observability

12.1 Metrics Collection

Application Metrics:

Request rate (requests per second)
Response time (p50, p95, p99)
Error rate (4xx, 5xx responses)
Active users/sessions

System Metrics:

CPU usage per service
Memory usage per service
Disk I/O
Network traffic

Business Metrics:

Claims processed per hour
Members enrolled per day
Policies sold
Average claim processing time

12.2 Logging Strategy

Log Levels:

ERROR: Application errors, exceptions
WARNING: Potential issues, deprecations
INFO: Important business events
DEBUG: Detailed debugging (dev only)

Centralized Logging:

All logs to ELK stack
Structured logging (JSON format)
Include correlation IDs for request tracing
Retention: 30 days hot, 90 days archived

12.3 Alerting Rules

Critical Alerts:

Service down or unreachable
Database connection failures
High error rate (> 5%)
Disk space critical (> 90%)

Warning Alerts:

High CPU usage (> 80%)
High memory usage (> 85%)
Slow response times (> 1s)
Queue depth growing

12.4 Monitoring Tools

Prometheus + Grafana:

Real-time metrics dashboards
Custom alerts and notifications
Historical data analysis

ELK Stack (Optional):

Centralized log aggregation
Log search and analysis
Visualization and reporting

13. Security Considerations

13.1 Application Security

Authentication:

JWT tokens with expiration
Secure password hashing (bcrypt)
Multi-factor authentication (optional)
Account lockout after failed attempts

Authorization:

Role-based access control (RBAC)
Permission checks at API level
Row-level security for sensitive data
Audit logging for all actions

API Security:

Rate limiting per user/IP
Input validation and sanitization
SQL injection prevention (ORM)
XSS prevention
CSRF protection

13.2 Data Security

Encryption:

Data at rest: Database encryption
Data in transit: TLS 1.2+
Sensitive fields: Field-level encryption (biometric data)
Backups: Encrypted backups

PII Protection:

Minimal data collection
Data access logging
Data retention policies
Right to be forgotten (GDPR)

Biometric Data:

Encrypted storage
Strict access controls
Audit trail for all access
Never transmitted in plain text

13.3 Network Security

Infrastructure:

Private network for backend services
Firewall rules (iptables)
VPN for remote admin access
No direct internet access to database

DDoS Protection:

Rate limiting at load balancer
Connection limits
IP blacklisting

14. Disaster Recovery

14.1 Backup Strategy

Database Cluster Backups:

Read Replicas: Provide real-time standby copies (Replica 0, Replica 1, Replica N)
Full backup: Daily at 2 AM from master database
Incremental: Every 6 hours
WAL archiving: Continuous for point-in-time recovery
Retention: 30 days
Backup location: Separate physical storage from cluster

File Storage Backups:

Continuous replication to secondary local storage
Daily snapshots of local drive
Retention: 30 days

Configuration Backups:

Infrastructure as Code (Git)
Docker Compose files versioned
Environment variables secured

14.2 Recovery Procedures

Database Cluster Recovery:

Stop all application services
Restore master from latest backup
Apply WAL logs for point-in-time recovery
Rebuild replication from master to all replicas
Verify data integrity and replication status
Restart all services

Service Recovery:

Pull latest Docker images
Deploy via Docker Swarm
Run health checks
Verify functionality

Master Database Failover Process:

Detect master database failure via health checks
Promote most up-to-date read replica to new master
Reconfigure remaining replicas to follow new master
Update application connection strings to new master
Restart Django and Celery services
Monitor replication lag and application health
Investigate and repair failed master (or provision new)

14.3 Recovery Objectives

RTO (Recovery Time Objective): 4 hours
RPO (Recovery Point Objective): 15 minutes

15. Summary

This Design system presents the following benefits.

Simple to maintain: One codebase, one database cluster, reduced operational overhead
Easy to develop: No service boundaries, standard Django development practices
Straightforward debugging: Single application with clear stack traces
Fast iteration: No need to coordinate multiple service deployments
Scalable: Can handle significant load with horizontal scaling
Cost-effective: Fewer resources and lower infrastructure complexity than microservices
Migration path: Can extract services later if business needs evolve

Table of Contents​

1. Overview​

1.1 Key Characteristics​

1.2 Why This Architecture?​

2. Architecture Philosophy​

2.1 Modular Monolith Principles​

2.2 What We're NOT Doing​

3. High-Level Architecture​

4. System Components​

4.1 Client Applications​

4.1.1 Admin Portal (React)​

4.1.2 Member Portal (React)​

4.1.3 Provider Portal (React)​

4.1.4 Agent Portal (React)​

4.1.5 BI Dashboard (React)​

4.1.6 Mobile App (Flutter)​

4.1.7 Access Patterns & Subdomains​

4.2 Core API (Django)​

Module Overview​

API Design Guidelines​

Base URL Structure​

API Endpoint Patterns​

Response Format Standards​

HTTP Status Codes​

Authentication & Authorization​

Query Parameters​

Field Selection & Expansion​

Error Codes​

Rate Limiting​

4.2.1 Authentication Module​

4.2.1.1 Short Description​

4.2.1.2 Users and Roles​

4.2.1.3 Dependency Graph​

4.2.1.4 High-level Flow Diagram​

4.2.1.5 Features List​

4.2.1.6 User Journey​

4.2.1.7 Database Design​

4.2.1.8 Exposed APIs​

4.2.2 Membership Module​

4.2.2.1 Short Description​

4.2.2.2 Users and Roles​

4.2.2.3 Dependency Graph​

4.2.2.4 High-level Flow Diagram​

4.2.2.5 Features List​

4.2.2.6 User Journey​

4.2.2.7 Database Design​

4.2.2.8 Exposed APIs​

4.2.3 Sales Module​

4.2.3.1 Short Description​

4.2.3.2 Users and Roles​

4.2.3.3 Dependency Graph​

4.2.3.4 High-level Flow Diagram​

4.2.3.5 Features List​

4.2.3.6 User Journey​

4.2.3.7 Database Design​

4.2.3.8 Exposed APIs​

4.2.4 Underwriting Module​

4.2.4.1 Short Description​

4.2.4.2 Users and Roles​

4.2.4.3 Dependency Graph​

4.2.4.4 High-level Flow Diagram​

4.2.4.5 Features List​

4.2.4.6 User Journey​

4.2.4.7 Database Design​

4.2.4.8 Exposed APIs​

4.2.5 Claims Module​

4.2.5.1 Short Description​

4.2.5.2 Users and Roles​

4.2.5.3 Dependency Graph​

4.2.5.4 High-level Flow Diagram​

4.2.5.5 Features List​

4.2.5.6 User Journey​

4.2.5.7 Database Design​

4.2.5.8 Exposed APIs​

4.3 Celery Worker Pools​

4.3.1 Worker Types & Task Queues​

4.3.2 Task Routing Strategy​

4.3.3 Scaling Strategy​

4.4 FastAPI AI/ML Service​

4.4.1 Why Separate?​

Table of Contents

1. Overview

1.1 Key Characteristics

1.2 Why This Architecture?

2. Architecture Philosophy

2.1 Modular Monolith Principles

2.2 What We're NOT Doing

3. High-Level Architecture

4. System Components

4.1 Client Applications

4.1.1 Admin Portal (React)

4.1.2 Member Portal (React)

4.1.3 Provider Portal (React)

4.1.4 Agent Portal (React)

4.1.5 BI Dashboard (React)

4.1.6 Mobile App (Flutter)

4.1.7 Access Patterns & Subdomains

4.2 Core API (Django)

Module Overview

API Design Guidelines

Base URL Structure

API Endpoint Patterns

Response Format Standards

HTTP Status Codes

Authentication & Authorization

Query Parameters

Field Selection & Expansion

Error Codes

Rate Limiting

4.2.1 Authentication Module

4.2.1.1 Short Description

4.2.1.2 Users and Roles

4.2.1.3 Dependency Graph

4.2.1.4 High-level Flow Diagram

4.2.1.5 Features List

4.2.1.6 User Journey

4.2.1.7 Database Design

4.2.1.8 Exposed APIs

4.2.2 Membership Module

4.2.2.1 Short Description

4.2.2.2 Users and Roles

4.2.2.3 Dependency Graph

4.2.2.4 High-level Flow Diagram

4.2.2.5 Features List

4.2.2.6 User Journey

4.2.2.7 Database Design

4.2.2.8 Exposed APIs

4.2.3 Sales Module

4.2.3.1 Short Description

4.2.3.2 Users and Roles

4.2.3.3 Dependency Graph

4.2.3.4 High-level Flow Diagram

4.2.3.5 Features List

4.2.3.6 User Journey

4.2.3.7 Database Design

4.2.3.8 Exposed APIs

4.2.4 Underwriting Module

4.2.4.1 Short Description

4.2.4.2 Users and Roles

4.2.4.3 Dependency Graph

4.2.4.4 High-level Flow Diagram

4.2.4.5 Features List

4.2.4.6 User Journey

4.2.4.7 Database Design

4.2.4.8 Exposed APIs

4.2.5 Claims Module

4.2.5.1 Short Description

4.2.5.2 Users and Roles

4.2.5.3 Dependency Graph

4.2.5.4 High-level Flow Diagram

4.2.5.5 Features List

4.2.5.6 User Journey

4.2.5.7 Database Design

4.2.5.8 Exposed APIs

4.3 Celery Worker Pools

4.3.1 Worker Types & Task Queues

4.3.2 Task Routing Strategy

4.3.3 Scaling Strategy

4.4 FastAPI AI/ML Service

4.4.1 Why Separate?